.TH clreq 1 "31 October 2008" "TrueCL Commands"

.SH NAME
clreq \- Issue a cluster request

.SH SYNOPSES
.TS
l l.
clreq	[\fB--parallel\fP|\fB--firstonly\fP] [\fB--encryption\fP=\fIkey\fP|\fIrsa\fP]
	[\fB--hosts\fP \fIX[,...]\fP|\fB--all\fP] [\fB--timeout\fP \fIN\fP] \fB--\fP \fBcmd [\fIarg value ...\fP]
.TE

.SH DESCRIPTION
The \fIclreq(1)\fP command is a generic interface to issue commands to one or
more TrueCL cluster nodes. It communicates with a \fIclreqd(1)\fP daemon on 
each node in question.

.SH ARGUMENTS
.TP 8
--parallel
By default each of the nodes to query are done so in turn. This flag will
result in the query being performed in parallel across the nodes - which can
save significant time for slower requests in clusters with a large number of 
nodes.
.TP
--firstonly
This will attempt to query all nodes in the cluster in parallel, but only
shows the results from the first node that returns one. After that all 
remaining requests from the nodes that have not responded will be discarded.
This is used occasionally for internal requests, but can be used
on the command line too. 
.TP
--encryption
The type of encryption used for the communication is usually determined by
the environment variable TRUECL_PKI. If this is set to 0 then 'key' based
encryption is used, setting to '1' uses RSA encryption. 

This option can be used to overcome the default, though is often not used.
Note that the daemon will have being configured to run with a particular
encryption scheme and will only respond to requests using that protocol.
.TP
--hosts
A comma-separated lists to send the request to. If neither this nor the
\fB--all\fP arguments are specified the request is handled by the local
machine.
.TP
--all
This indicates that the request should be sent to all nodes in the 
cluster. Of course if nodes are not available it may take time for all the
responses to appear.
.TP
--timeout
The default timeout when waiting for a response is 10 seconds. This is usually 
adequate. However this argument can be used to specify an alternative [given in
seconds].
.TP
--
This is used to indicate that argument processing should be stopped. Typically
used when the request being issued also has arguments that should not be
processed as part of the \fIclreq(1)\fP request.
.SH OUTPUT
Standard output is used to show the results of the request. Each line generated
is prefixed with the name of the node the results present, followed by a white
space. This is the case even when a single node is returning results.

If the request produces an error the result will still be present on standard
output. Standard error output is used if the \fIclreq(1)\fP command fails to
function as expected.

.SH EXIT CODES
If the request can be satisfied, even if the request itself is considered a
failure then a zero will be returned. Otherwise a general failure is 
indicated by a return code of 1.

.SH NOTES
The typical day-to-day operation of a TrueCL cluster probably requires little
use of this utility. However it offers a useful way to checking and managing 
the cluster. Administrators are encouraged to view the \fIclreqd_cmds(5)\fP
manual page details of the available commands.

.SH AUTHOR
The TrueCL software was written by Simon Edwards, (C) 2006-2008, working
for Advantsys Computer Services Ltd - www.advantsys.co.uk.

.SH SEE ALSO
.BR clreqd(1),
.BR clreqd_cmds(1)

.SH AVAILABILITY
This utility was specifically written under the GNU GPL license and as required
by such software comes with \fIno warranty or guarantee of any kind\fP. For
more information, please see the following page: truecl.advantsys.co.uk.

